Copyright (c) 1991-1993 Borland International, Inc. All Rights Reserved. THE EXPRESSION BUILDER ---------------------- Use the Expression Builder to build valid dBASE expressions and insert them into the text editor, the Command window, and certain dialog box fields. Contents -------- I. What the Expression Builder does II. How to display the Expression Builder III. The GETEXPR() function IV. About the Expression window and the Safety Net mode V. Building expressions using the Category, Type, and Paste list boxes VI. How to paste an element into the Expression window VII. Specifying a result type VIII. About the Safety Net IX. Editing constants X. Using Undo and Group XI. Keyboard Quick Reference XII. Using the DBASEWIN.FNF table to modify the list of functions What the Expression Builder does -------------------------------- The Expression Builder only builds expressions. It does not assign anything. When you build an expression in the Expression Builder and then click the OK button, the expression is inserted into the environment from which you called the Expression Builder. How to display the Expression Builder ------------------------------------- There are four ways to display the Expression Builder: - Use the GETEXPR() function in the Command window or in a program. - Press the Expression Builder button (currently, the rightmost button) on the SpeedBar. - Select Build Expression from the Edit menu. - Press Ctrl+E. If any text is selected in the Command window or in the text editor when you call the Expression builder, that text will appear in the Expression window as the default expression to be edited. You can also use the Expression Builder when you are in FOR() or WHILE() fields in certain dialog boxes. The GETEXPR() function ---------------------- The syntax of GETEXPR() is as follows: GETEXPR( [ [ , [ , ] ] ] ) where: is a string that will appear in the Expression window as the default expression to be edited. is a string that appears as the title on the Expression Builder title bar is the desired result type. This result type appears in the Result Type list box in the Expression Builder. can be "C", "N", "L", "D", or "X". The "X" means 'Any' result type. The default is "X". Examples: GETEXPR() X = GETEXPR() X = GETEXPR("","Create a Filter Expression","L") X = GETEXPR(X) About the Expression window and the Safety Net mode --------------------------------------------------- You build expressions in the Expression Builder's Expression window. There are two modes available: - With the Safety Net on, you select valid elements from a list and paste them into the Expression window. - With the Safety Net off, you can select and paste elements, as above, but you can also type expressions directly into the Expression window. In either case, the Expression Builder does not let you insert the expression into the calling environment unless the expression is valid. To toggle the Safety Net on and off, check and uncheck the Safety Net check box at the top of the Expression Builder. Building expressions using the Category, Type, and Paste list boxes ------------------------------------------------------------------- Use the three list boxes in the lower half of the Expression Builder to display valid items that can be used to build an expression. The items in the leftmost box are the most general, and those in the rightmost list box are the most specific. Move from left to right, selecting which items to show, and then choose an item from the rightmost list box (the Paste list box) to paste into the Expression window. The three list boxes are explained below: - The Category list box lists the main categories of items you can use to create an expression. These categories are "Constant," "Field," "Function," "Operator," and "Variable." - The Type/Table list box shows subcategories of whatever category is selected in the Category list box. (When you choose "Field" from the Category list box, the Type/Table list box displays a list of all open tables.) - The Paste list box shows all the elements that are named by the subcategory selected in the Type/Table list box. Some possible combinations are as follows: If you select this And then select this These items appear item from the item from the Type/ in the Paste list Category list box... Table list box... box... -------------------- ---------------------- --------------------- "Function" "Data type conversion" All the dBASE functions that can be used for converting data types "Field" a table name All the fields in the selected table "Variable" "User" All the user-defined variables currently in memory How to paste an element into the Expression window -------------------------------------------------- To paste an element from the Paste list box into the Expression window, do one of the following: - Using the mouse, - Double-click the desired item in the Paste list box, or - Drag the desired item from the Paste list box to the Expression window - Using the keyboard 1. Select an item from the Paste list box (either by clicking once with the mouse or by navigating to the item with the keyboard), then 2. Press the Space bar The item is pasted into the Expression window at the cursor position in the window. When the Safety Net is off, you can use standard Windows key combinations to cut, copy, and paste text in the Expression window. For example, Ctrl+X cuts text, Ctrl+C copies text to the clipboard, and Ctrl+V inserts text from the clipboard. Specifying a result type ------------------------ By default, the Expression Builder accepts any data type for the result of an expression. However, you can specify what data type the expression must evaluate to, in order to be considered valid. Choose a data type from the Result Type list. The options are "Any," "Character," "Date," "Logical," and "Numeric." If you choose any of these choices other than "Any," the expression must evaluate to the selected data type in order to be valid. If the result is the wrong data type, the message "Wrong result type..." is displayed in the information box (located below the three list boxes), and the OK button is dimmed. About the Safety Net -------------------- When the Safety Net is on (i.e., when the Safety Net check box is checked): - You must select items from the Paste list box and paste them into the Expression window. That is the only way to insert items into the expression. You cannot type elements directly into the Expression window when the Safety Net is on, except for constants--see below under "Editing Constants." - Bladerunner tries to validate the expression every time you insert a new item. If the expression is valid, the result of the expression is shown in the information box directly below the Expression window. If the expression is invalid, a message explaining the problem is displayed, and the OK button is dimmed. This always happens when you insert a token that must be replaced with a valid operator or operand. - Colored placeholder elements, or "tokens," are inserted to show elements missing from your expression. A white "Op" means you must insert an operator. A yellow text string means you must insert an operand. The text string tells you what kind of operand is required. - The cursor in the Expression window is between elements, never within an element. When the Safety Net is off: - You can type directly into the Expression window. - The Expression Builder does not try to validate your expression until you choose the OK button. If the expression is invalid, the OK button is dimmed so you cannot insert the invalid expression into the calling environment. - The result of the expression that you are building is not shown in the information box. If you are working with the Safety Net off and you want to see the result of the expression without leaving the Expression Builder, turn the Safety Net on. The expression will be evaluated and the result shown in the information box. You can only turn Safety Net on or off if the expression is valid. The information box below the expression tells you the state of your expression. Editing constants ----------------- When the Safety Net is on, you can type constants directly into the Expression window. This is the only time you can type directly into the Expression window when you are in Safety Net mode. To type a constant into the Expression window when the Safety Net is on, you first must insert a constant. Follow these directions: 1. Select "Constant" from the Category list box. 2. Select a type of constant from the Type/Table list box. 3. Choose a constant from the Paste list box by double-clicking it, dragging it into the Expression window, or by selecting (highlighting) it and then pressing the space bar. 4. Then either - Put the cursor next to the constant in the Expression window and start typing, or - Right-click the mouse near the constant in the Expression window. In either case, a text box appears where you can type (or finish typing) the constant. 5. Press the Tab key or the Enter key to finish. You cannot insert illegal characters for the constants, e.g., you can't insert a character for a numeric constant. Using Undo and Group -------------------- Click the Undo button (in the upper-right corner) to undo the last operation. To group items in the Expression window, i.e., to put parentheses around them, highlight the items and click the Group button (in the upper-right corner). Keyboard Quick Reference ------------------------ These keystrokes work the same whether the Safety Net is on or off, with the exception of the Left and Right arrows, as noted below: Home Move cursor to end of line End Move cursor to beginning of line PgUp Move cursor up multiple lines PgDown Move cursor down multiple lines Up Arrow Move cursor up one line Down Arrow Move cursor down one line Left Arrow Move cursor left one expression element: one character when Safety Net is off, or one token when Safety Net is on Right Arrow Move cursor right one expression element: one character when Safety Net is off, or one token when Safety Net is on Ctrl + Home Move cursor to beginning of expression Ctrl + End Move cursor to end of expression The Shift key causes any of the above keystrokes to extend the current selection. Using the DBASEWIN.FNF table to modify the list of functions ------------------------------------------------------------ Information about the functions that are displayed in the Paste list box and that can be pasted into the Expression window is stored in a table called DBASEWIN.FNF. You can add records to this table to add your own user-defined functions (UDFs) to the Expression Builder. DBASEWIN.FNF contains the following required fields. Field Name Description ----- ------------------------------------------ NAME Name of the function, e.g., TAGCOUNT. NAME_EXT One or more dots (periods) to indicate that there is one or more possible versions of this function, depending on which arguments are used. For example, TAGCOUNT appears in the NAME field in two records. The first record has one dot in the NAME_EXT field, and the second record has two dots in the NAME_EXT field. When the first version is chosen in the Paste list box, the following form of the function is pasted: TAGCOUNT(.mdx filename) When the second version is chosen, the following form of the function is pasted: TAGCOUNT(.mdx filename, database alias) The arguments are taken from the ARGUMENTS field (see below). ARGUMENTS Comma-delimited list of arguments for the function named in the NAME field. (See also the explanation for the NAME_EXT field.) CATEGORIES Comma-delimited list of language element types that are displayed in the Type list box. PURPOSE The purpose of the function. USERHELP (To be added later.) The field names listed above cannot be changed. Other fields can be added, but they are ignored by the Expression Builder. All fields are character data type. The size of the fields can be changed. When you highlight a function in the Paste list box of the Expression Builder, information from the DBASEWIN.FNF table is displayed in the information box, as explained below: First line: This text is constructed from 1) the name in the NAME field, 2) open parenthesis, 3) the arguments from the ARGUMENTS field, 4) close parenthesis. Second line: the text from the PURPOSE field.